.TH rename 3 "" "" ""
.SH SYNOPSIS
rename \- rename a file
.SH ANSI_SYNOPSIS
#include <stdio.h>
.br
int rename(const char *
.IR old ,
const char *
.IR new );
.br

int _rename_r(void *
.IR reent ,
.br
const char *
.IR old ,
const char *
.IR new );
.br
.SH TRAD_SYNOPSIS
#include <stdio.h>
.br
int rename(
.IR old ,
.IR new )
.br
char *
.IR old ;
.br
char *
.IR new ;
.br

int _rename_r(
.IR reent ,
.IR old ,
.IR new )
.br
char *
.IR reent ;
.br
char *
.IR old ;
.br
char *
.IR new ;
.br
.SH DESCRIPTION
Use 
.BR rename 
to establish a new name (the string at 
.IR new )
for a
file now known by the string at 
.IR old .
After a successful
.BR rename ,
the file is no longer accessible by the string at 
.IR old .

If 
.BR rename 
fails, the file named 
.BR *<[old >>
is unaffected. The
conditions for failure depend on the host operating system.

The alternate function 
.BR _rename_r 
is a reentrant version. The
extra argument 
.IR reent 
is a pointer to a reentrancy structure.
.SH RETURNS
The result is either 
.BR 0 
(when successful) or 
.BR -1 
(when the file
could not be renamed).
.SH PORTABILITY
ANSI C requires 
.BR rename ,
but only specifies that the result on
failure be nonzero. The effects of using the name of an existing file
as 
.BR *<[new >>
may vary from one implementation to another.

Supporting OS subroutines required: 
.BR link ,
.BR unlink ,
or 
.BR rename .
.SH SOURCE
src/newlib/libc/stdio/rename.c
